Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

GetMaxCompressionSize

The GetMaxCompressionSize function allows your application to determine the maximum size an image will be after compression. You specify the compression characteristics, including compression type and quality, along with the image.

pascal OSErr GetMaxCompressionSize (PixMapHandle src,
                                         const Rect *srcRect,
                                         short colorDepth,
                                         CodecQ quality,
                                         CodecType cType,
                                         CompressorComponent codec,
                                         long *size);


src

Contains a handle to the source image. The source image must be stored in a pixel map structure. The compressor uses only the image's size and pixel depth to determine the maximum size of the compressed image.

srcRect

Contains a pointer to a rectangle defining the portion of the source image that is to be compressed. You may set this parameter to nil if you are interested only in information about quality settings. GetCompressionTime then uses the bounds of the source pixel map.

colorDepth

Specifies the depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components" for more information on the GetCodecInfo function).

quality

Specifies the desired compressed image quality. See "Compression Quality Constants," for valid values.

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types).

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

size

Contains a pointer to a field to receive the size, in bytes, of the compressed image.

GetCompressionTime

The GetCompressionTime function allows your application to determine the estimated amount of time required to compress a given image. This function also allows you to verify that the quality settings you desire are supported by a given compressor component.

You specify the compression characteristics, including compression type and quality, along with the image.

pascal OSErr GetCompressionTime (PixMapHandle src,
                                         const Rect *srcRect,
                                         short colorDepth,
                                         CodecType cType,
                                         CompressorComponent codec,
                                         CodecQ *spatialQuality,
                                         CodecQ *temporalQuality,
                                         unsigned long *compressTime);


src

Contains a handle to the source image. The source image must be stored in a pixel map structure. The compressor uses only the bit depth of this image to determine the compression time. You may set this parameter to nil if you are interested only in information about quality settings.

srcRect

Contains a pointer to a rectangle defining the portion of the source image to compress. You may set this parameter to nil if you are interested only in information about quality settings. GetCompressionTime then uses the bounds of the source pixel map.

colorDepth

Specifies the depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components" for more information on the GetCodecInfo function).

cType

Specifies a compressor type. You must set this parameter to a valid compressor type (see Table 3 for a list of the available compressor types).

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

spatialQuality

Contains a pointer to a field containing the desired compressed image quality. The Image Compression Manager sets this field to the closest actual quality that the compressor can achieve. See "Compression Quality Constants," for valid values. If you are not interested in this information, pass nil in this parameter.

temporalQuality

Contains a pointer to a field containing the desired temporal quality. Use this value only with images that are part of image sequences. The Image Compression Manager sets this field to the closest actual quality that the compressor can achieve. See "Compression Quality Constants," for valid values. If you are not interested in this information, pass nil in this parameter.

compressTime

Contains a pointer to a field to receive the compression time, in milliseconds. If the compressor cannot determine the amount of time required to compress the image or if the compressor does not support this function, this field is set to 0. If you are not interested in this information, pass nil in this parameter.

GetSimilarity

The GetSimilarity function compares a compressed image to a picture stored in a pixel map and returns a value indicating the relative similarity of the two images.

pascal OSErr GetSimilarity (PixMapHandle src, const Rect *srcRect,
                                          ImageDescriptionHandle desc, Ptr data,
                                          Fixed *similarity);


src

Contains a handle to the noncompressed image. The image must be stored in a pixel map structure.

srcRect

Contains a pointer to a rectangle defining the portion of the image to compare to the compressed image. This rectangle should be the same size as the image described by the image description structure specified by the desc parameter.

desc

Specifies a handle to the image description structure that defines the compressed image for the operation.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address.

similarity

Contains a pointer to a field that is to receive the similarity value. The compressor sets this field to reflect the relative similarity of the two images. Valid values range from 0 (completely different) to 1.0 (identical).

GetCompressedImageSize

The GetCompressedImageSize function determines the size, in bytes, of a compressed image.

Most applications do not need to use this function because compressed images have a corresponding image description structure with a size field. You only need to use this function if you do not have an image description structure associated with your data--for example, when you are taking a compressed image out of a movie one frame at a time.

pascal OSErr GetCompressedImageSize (ImageDescriptionHandle desc,
                                         Ptr data, long bufferSize,
                                         ICMDataProcRecordPtr dataProc,
                                         long *dataSize);


desc

Specifies a handle to the image description structure that defines the compressed image for the operation.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address.

bufferSize

Specifies the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

dataProc

Points to a data-loading function structure. If the data stream is not all in memory when your program calls GetCompressedImageSize , the compressor calls a function you provide that loads more compressed data (see "Data-Loading Functions," for more information about data-loading functions). If you have not provided a data-loading function, set this parameter to nil . In this case, the entire image must be in memory at the location specified by the data parameter.

dataSize

Contains a pointer to a field that is to receive the size, in bytes, of the compressed image.